feat(chatgpt-unblock): route an app that opened before opencodex - #6381

Summary

Stacked on the maintainer's intercept split #6365. New here: the watcher commit (route an app that opened before opencodex), its docs follow-up, and one gate fix the merge with current dev needed (below). A pull request in this repository can only target a branch of this repository, so this one targets dev and its diff also shows #6365 until that lands; I will rebase it onto dev then, and the diff will shrink to this one commit. Please review it after #6365.

Problem. At login macOS reopens the ChatGPT desktop app at about the same moment the opencodex service starts. If the app wins the race, the launch watcher wakes on the app's SingletonLock, finds no listener on the intercept port, and exits. The app then stays on native networking until its next launch. Nothing orders the two at login: the app is reopened by the session, and the proxy by its own launchd service.

Change.

• When the intercept listener is up, startChatgptUnblock rewrites a readiness marker, chatgpt-unblock.ready, in the config dir. The watcher's launchd agent now has two WatchPaths: the app's SingletonLock and this marker. Whichever of the app and opencodex comes up second triggers the watcher, which routes the app.
• The marker is also rewritten on every opencodex restart. So in watch mode the watcher only restarts an app that started within the last five minutes (ps -o etime=, [[dd-]hh:]mm:ss). An opencodex restart in the middle of a session does not quit an app that has been open longer than that. This is an age check, not an activity check. An elapsed time that cannot be read counts as a fresh launch. ocx chatgpt launch still always acts.
• Writing the marker is best effort. Without it, the watcher still acts on the app's next launch, as before.
• The guide's watcher paragraph in all eight locales describes both triggers and the five-minute rule. Carried from the split and kept: app lookup by pgrep -a -x ChatGPT, bash -n on the generated script, and the shim env through the shared launch script.
• ocx chatgpt status compares the installed agent plist with one built from the same two watch paths, so a fresh install reads as current.

Verification

Head b67f60385 merges dev fe09557cb. The only conflicts were in the CLI capability registry, which dev split into per-area files: the ocx chatgpt entry moved to src/cli/capabilities-base.ts with this branch's text, help.ts keeps dev's lab line and this branch's chatgpt line, and bun run skill:surface regenerated the ocx skill reference (skill:surface:check passes). On this head, bun run typecheck, structure:check and privacy:scan pass. tests/clients/desktop-*, tests/config/, the CLI chatgpt/capabilities/help/registry tests, skill-ocx, test-layout-tooling, socks5-handshake and core-lab-boundary give 1334 pass, 5 fail across 85 files. The 5 failures are in cli-help-navigation, cli-help-recovery and cli-help-paths, and the same 5 fail on unmodified dev fe09557cb on this machine.

• b185b4e2c merges the current dev tip again (0 behind; dev had moved 100 commits). Four conflicts, resolved as follows:

  • src/cli/chatgpt-command.ts keeps feat(chatgpt): local-CA send-unblock intercept, stacked on #6361 (split from #5947) #6365's intercept subcommands and adopts dev's bundle trust check (0358e72c8, from fix(chatgpt): validate bundle trust before restore #6453). That check now runs before every relaunch path, the intercept one included: after the intercept listener probe and the shim's binary resolution, and before the restore watcher guard.
  • gate-rewrite.ts: dev already has the same used_percent change as c74fa3c884 here (f5572a003, from fix(chatgpt): read the usage window as used_percent too in the gate rewrite #6463), so it is no longer part of this diff. Only the comment differed.
  • structure/config.md and the ChatGPT desktop guide keep both sides.
  • The bundle-trust command-child fixture now stubs the intercept status and watcher modules, so its status and restore scenarios never probe the host's listener, launchd agent, keychain or running proxy. A new scenario covers restore refusing while the watcher is loaded.
  • The desktop-unblock layout entries share lines, keeping tests/fixtures/test-layout-expected.json under the 2000-line ratchet the way dev's packed entries do.

• 9c6dc704b makes the dropped CODEX_CLI_PATH testable: the open stub records the value it inherits, and three tests seed one and check native restore, a launch without the shim, and a shim launch (only the shim launcher in --env). They fail with unset CODEX_CLI_PATH removed. tests/clients/desktop-unblock-launch-script.test.ts: 45 pass, 0 fail.

• On b185b4e2c: bun run typecheck, bun run structure:check, bun run privacy:scan and bun run skill:surface:check pass. All 33 tests/clients/ desktop and ChatGPT files: 449 pass, 2 skip, 0 fail. The file-size ratchet and test-layout suites: 27 pass.

• The first dev merge (71bce164f) resolved as if feat(chatgpt): local-CA send-unblock intercept, stacked on #6361 (split from #5947) #6365's intercept commits and the watcher commits were replayed onto dev, without the pre-squash shim commit that dev already has in its hardened form. It exposed one real regression, fixed in c74fa3c884: the intercept's web usage snapshot (used_percent) stopped opening a genuinely exhausted gate. A web snapshot below 100% stays closed (new test).

• bun test ./tests/clients/ ./tests/ci-workflows/ ./tests/config/ ./tests/lib/socks5-handshake.test.ts ./tests/lab/core-lab-boundary.test.ts ./tests/test-layout.test.ts ./tests/test-layout-tooling.test.ts on 4d80aaaae: 3524 pass, 9 skip, 0 fail.

• 4d80aaaae restores guards the merged launch script had lost from feat(chatgpt): local-CA send-unblock intercept, stacked on #6361 (split from #5947) #6365's version: a failed open now exits non-zero instead of printing success, an explicit launch that meets another run's lock fails with a message, and the inherited CODEX_CLI_PATH is dropped. Three new tests cover them and fail against the previous script.

• New tests:

  • the script restarts an app that started 4:59 ago and leaves one that started 5:01, 2:03:04 or 1-02:03:04 ago (ports of the same tests from the pre-split branch);
  • a missing or unparseable elapsed time counts as a fresh launch;
  • the explicit launch command restarts an old app;
  • the agent plist lists both watch paths, and the installed agent watches the marker;
  • a started intercept writes the marker;
  • a freshly installed agent plist reads as up to date.

• The age, watch-path and install tests fail against the previous launch-watcher.ts, and all pass with this commit.

• Live, on the author's Mac (macOS 26.5.1), with the proxy running as the launchd service:

  • rewriting the marker unchanged woke the watcher, which logged that the app already carried the switches and did not restart it;
  • after a reboot, the service came back and wrote the marker, and the app ended up routed with its switches and the app-server launcher (24 connections to the listener).

• Not run: a reboot in which the app is proven to have started before the listener. The live reboot shows the end state, not the order.

• 336044304: merged dev (0 behind; feat(chatgpt): local-CA send-unblock intercept, stacked on #6361 (split from #5947) #6365 head f89bffc3c unchanged and still included). Conflicts resolved: the launch refusal keeps this branch's shim-or-intercept opt-in and adds fix(chatgpt): say why a dropped chatgptDesktop block reads as off #6486's dropped-block reason; the chatgptDesktop schema now lives in src/config/schema/chatgpt-desktop.ts from dev and is extended here with unblockSend and port (strict, so without them the intercept block would be dropped); tests that used unblockSend as the leftover key use unblockPort on this branch; structure/config.md keeps both sentences within its 600-line budget. bun run typecheck, bun run structure:check, bun run privacy:scan pass; tests/clients/desktop-*, ChatGPT and config suites, socks5-handshake and test-layout-tooling (68 files): 1035 pass, 0 fail.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. (Structure doc and the guide's watcher paragraph in all eight locales.)
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (The marker holds a port number and a timestamp, is written 0644 in the config dir, and only wakes the existing watcher. The watcher's new behaviour only restricts when it restarts the app.)

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Co-authored-by: JUN jun@lidgeai.com

Summary by CodeRabbit

• New Features
  • Added an experimental, opt-in macOS ChatGPT desktop TLS intercept that removes quota-related send blocks while preserving other eligibility restrictions. It rewrites eligible HTTP and SSE responses and relays WebSocket traffic unchanged.
  • Added ocx chatgpt commands to launch, restore, and check status, plus install or remove an optional launch watcher. The intercept can be enabled independently of the app-server shim and requires a running proxy and trusted local certificate. Its listener port can be configured.
• Documentation
  • Expanded setup guidance with certificate trust, network behavior, watcher operation, and feature limitations.